1   /*
2    * Copyright (C) 2008 The Guava Authors
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    * http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package com.google.common.collect.testing;
18  
19  import com.google.common.annotations.GwtCompatible;
20  
21  import java.util.Collection;
22  import java.util.List;
23  import java.util.Map;
24  
25  /**
26   * To be implemented by test generators of things that can contain
27   * elements. Such things include both {@link Collection} and {@link Map}; since
28   * there isn't an established collective noun that encompasses both of these,
29   * 'container' is used.
30   *
31   * @author George van den Driessche
32   */
33  @GwtCompatible
34  public interface TestContainerGenerator<T, E> {
35    /**
36     * Returns the sample elements that this generate populates its container
37     * with.
38     */
39    SampleElements<E> samples();
40  
41    /**
42     * Creates a new container containing the given elements. TODO: would be nice
43     * to figure out how to use E... or E[] as a parameter type, but this doesn't
44     * seem to work because Java creates an array of the erased type.
45     */
46    T create(Object ... elements);
47  
48    /**
49     * Helper method to create an array of the appropriate type used by this
50     * generator. The returned array will contain only nulls.
51     */
52    E[] createArray(int length);
53  
54    /**
55     * Returns the iteration ordering of elements, given the order in
56     * which they were added to the container. This method may return the
57     * original list unchanged, the original list modified in place, or a
58     * different list.
59     *
60     * <p>This method runs only when {@link
61     * com.google.common.collect.testing.features.CollectionFeature#KNOWN_ORDER}
62     * is specified when creating the test suite. It should never run when testing
63     * containers such as {@link java.util.HashSet}, which have a
64     * non-deterministic iteration order.
65     */
66    Iterable<E> order(List<E> insertionOrder);
67  }